---
title: "submit_appworx_job stored procedure documentation"
summary: "Analysis of the Oracle standalone procedure that queues Appworx batch job requests, including business rules and operations."
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-21
source_schema: "WCIS_DBA"
source_name: "submit_appworx_job"
source_type: "PROCEDURE"
oracle_status: "found"
---

# submit_appworx_job

## Overview

| Field | Value |
| --- | --- |
| **Schema** | WCIS_DBA |
| **Type** | Standalone Procedure |
| **Database** | Oracle (resolved via caller's data portal by default; `PRADT`@`WCISPROD`/`WCISDEV1` on the override path) |
| **Calling libraries** | `SAIF.Services.Appworx` |
| **Calling classes** | `clsRequestAppworxJob` |

## Purpose

Queues a single batch job request row into the Appworx scheduler's `JOB_QUEUE` table. This is the sole application-layer SQL statement issued by `SAIF.Services.Appworx`; the .NET code contains no SQL text of its own, only the bare procedure name and named parameter bindings (see [SQL-001](../sql/SQL-001-submit-appworx-job.md)).

## Procedures Methods

### submit_appworx_job

| Field | Value |
| --- | --- |
| **Returns** | None (procedure; no OUT parameters, no return value) |
| **Called by** | `clsRequestAppworxJob.SubmitBatchJob` (instance) |

**Description:** Generates a new scheduler job identifier from the `SO_MAX_JOBID` sequence, then inserts a row into `JOB_QUEUE` capturing the module, requestor, generated job id, the standalone-job marker (`-1`), and all 20 positional argument slots. A `NO_DATA_FOUND` condition is silently swallowed; any other exception is re-raised unchanged.

#### Parameters

| Parameter | Direction | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `inmodule` | IN | VARCHAR2 | — | Appworx module/job name to run; inserted into `JOB_QUEUE.MODULE`. |
| `inrequestor` | IN | VARCHAR2 | — | Requesting system/user label; inserted into `JOB_QUEUE.REQUESTOR`. |
| `inprinter` | IN | VARCHAR2 | — | Target printer/output destination; accepted but never persisted (see PR-004 below). |
| `inarg1`–`inarg20` | IN | VARCHAR2 | `''` | Positional job arguments; each inserted into the matching `ARG_1`–`ARG_20` column. |

## Business Rules

Rules extracted from this procedure's logic:

| Rule ID | Rule | Condition | Action |
| --- | --- | --- | --- |
| PR-001 | Every job submission is assigned a unique scheduler job identifier generated by the database, never supplied by the caller. | Always, at the start of every invocation | `SELECT so_max_jobid.NEXTVAL INTO v_jobid FROM DUAL;` — the sequence value is written to `JOB_QUEUE.JOBID` |
| PR-002 | Jobs submitted through this entry point are always standalone (top-level) jobs, never children of a master job. | Always | `MASTER_JOB_NUMBER` is inserted as the hard-coded literal `-1` |
| PR-003 | Argument slots the caller does not supply are stored as empty rather than rejected — the procedure accepts a variable-length argument list. | Any of `inarg1`..`inarg20` omitted by the caller | Each `inargN` formal declares `DEFAULT ''`, so the omitted slot is inserted as an empty string (Oracle stores `''` as `NULL`) into the matching `ARG_n` column |
| PR-004 | The printer destination is accepted but not persisted by this procedure — it does not participate in the queued job row. | Always | `inprinter` is declared as a required `IN` parameter but appears nowhere in the `INSERT` column or value list; it is silently discarded** |
| PR-005 | Module and requestor are mandatory on every submission — the procedure provides no fallback for them. | Always | `inmodule` and `inrequestor` are declared with no `DEFAULT`, so omitting them raises `PLS-00306` at call time; the supplied values are inserted into `JOB_QUEUE.MODULE` / `JOB_QUEUE.REQUESTOR` |
| PR-006 | A "no data found" condition during submission is deliberately swallowed and reported as success. | `NO_DATA_FOUND` raised anywhere in the body | `WHEN NO_DATA_FOUND THEN NULL;` — the exception is suppressed, the procedure returns normally, and the caller cannot distinguish this from a successful queue insert** |
| PR-007 | All other failures are propagated unchanged to the caller; the procedure performs no compensating action and no logging. | Any exception other than `NO_DATA_FOUND` | `WHEN OTHERS THEN RAISE;` — re-raised to the caller (which wraps it as an `ApplicationException` per [BR-006](../business-rules.md#br-006-submission-failures-are-wrapped-and-rethrown)). A source comment notes logging was considered but not implemented |
| PR-008 | The procedure performs no validation of the module name, requestor, printer, or argument content. | Always | No `IF`/`CASE`/constraint checks exist in the body — the only control flow is the sequence fetch, the insert, and the exception handler. Bad module names are queued and fail later in the scheduler** |
| PR-009 | Submission does not commit — transaction control is left entirely to the caller. | Always | No `COMMIT`, `ROLLBACK`, `SAVEPOINT`, or `PRAGMA AUTONOMOUS_TRANSACTION` appears in the body; the queued row becomes visible to the scheduler only when the caller's transaction commits (the BOF data portal governs this)** |

> These rules are documented in [business-rules.md](../business-rules.md). Newly introduced rules must be added to `business-rules.md` as part of the same writing task.

## Operations

Operations and processes implemented in this procedure:

| Operation | Description | Trigger |
| --- | --- | --- |
| Generate job identifier | Fetches the next value of the `SO_MAX_JOBID` sequence into `v_jobid` and uses it as the scheduler job identifier for the row about to be queued. | First statement of every invocation |
| Queue batch job request | Inserts a single row into `JOB_QUEUE` capturing the module, requestor, generated job id, the standalone-job marker (`-1`), and all 20 positional argument slots. | Immediately after the job identifier is generated |
| Suppress no-data condition | Catches `NO_DATA_FOUND` and returns normally without queuing, converting a data-absence failure into a silent no-op. | `NO_DATA_FOUND` raised during the sequence fetch or insert |
| Propagate failure | Re-raises any other exception unchanged so the calling application can surface it. | Any non-`NO_DATA_FOUND` exception |

> These operations are also listed in [operations-processes.md](../operations-processes.md) with source reference back to this document.

## Source Code

<details>
<summary>PL/SQL procedure body</summary>

```sql
PROCEDURE          submit_appworx_job (
   inmodule      IN   VARCHAR2,
   inrequestor   IN   VARCHAR2,
   inprinter     IN   VARCHAR2,
   inarg1        IN   VARCHAR2 DEFAULT '',
   inarg2        IN   VARCHAR2 DEFAULT '',
   inarg3        IN   VARCHAR2 DEFAULT '',
   inarg4        IN   VARCHAR2 DEFAULT '',
   inarg5        IN   VARCHAR2 DEFAULT '',
   inarg6        IN   VARCHAR2 DEFAULT '',
   inarg7        IN   VARCHAR2 DEFAULT '',
   inarg8        IN   VARCHAR2 DEFAULT '',
   inarg9        IN   VARCHAR2 DEFAULT '',
   inarg10       IN   VARCHAR2 DEFAULT '',
   inarg11       IN   VARCHAR2 DEFAULT '',
   inarg12       IN   VARCHAR2 DEFAULT '',
   inarg13       IN   VARCHAR2 DEFAULT '',
   inarg14       IN   VARCHAR2 DEFAULT '',
   inarg15       IN   VARCHAR2 DEFAULT '',
   inarg16       IN   VARCHAR2 DEFAULT '',
   inarg17       IN   VARCHAR2 DEFAULT '',
   inarg18       IN   VARCHAR2 DEFAULT '',
   inarg19       IN   VARCHAR2 DEFAULT '',
   inarg20       IN   VARCHAR2 DEFAULT ''
)
AS
   v_jobid   NUMBER;

BEGIN
   SELECT so_max_jobid.NEXTVAL
     INTO v_jobid
     FROM DUAL;

   INSERT INTO job_queue
               (module, requestor, master_job_number, jobid,
                arg_1, arg_2, arg_3, arg_4, arg_5, arg_6, arg_7, arg_8, arg_9, arg_10,
                arg_11, arg_12, arg_13, arg_14, arg_15, arg_16, arg_17, arg_18, arg_19, arg_20)
        VALUES (inmodule, inrequestor, -1, v_jobid,
                inarg1, inarg2, inarg3, inarg4, inarg5, inarg6, inarg7, inarg8, inarg9, inarg10,
                inarg11, inarg12, inarg13, inarg14, inarg15, inarg16, inarg17, inarg18, inarg19, inarg20);
EXCEPTION
   WHEN NO_DATA_FOUND
   THEN
      NULL;
   WHEN OTHERS
   THEN
      -- Consider logging the error and then re-raise
      RAISE;
END submit_appworx_job;
```

</details>

> **Note:** Statements marked with ** could not be confirmed; treat as unknown until verified.

## Related Documentation
- [Procedure catalog](index.md)
- [Business rules](../business-rules.md)
- [Operations and processes](../operations-processes.md)
- [SQL catalog](../sql/index.md)

## Sources
- Oracle DBA_SOURCE: WCIS_DBA.submit_appworx_job
- Calling code: `SAIF.Services.Appworx/clsRequestAppworxJob.vb`